home *** CD-ROM | disk | FTP | other *** search
/ .net (French) 1996 November / .net Magazine (FR) - Issue 01 - Nov 1996.iso / mac / FTP / Anarchie-160 / Documentation < prev    next >
Text File  |  1995-07-23  |  24KB  |  282 lines

  1. Anarchie v1.6.0 ⌐ 1993-95 Peter N Lewis
  2. This program is $10 shareware.
  3.  
  4. ╥I filled up my disk in 20 minutes!  Before Anarchie it would take
  5. me a good hour or more to download the same amount of stuff!╙ - Russell Baird
  6.  
  7. As seen on TV (MacNeil/Lehrer Show, May&October 1994)
  8.  
  9. As demoed at Apple╒s World Wide Developers Conference, May 1994
  10.  
  11. Second Place in the Best Scriptable Application category of the Everyday AppleScript¬ Contest, June 1994.
  12.  
  13. 4.5 stars - MacUser Sep 1994 (and they were using v1.1.3!)
  14.  
  15. Outstanding Programming for a Shareware Product, USENet Macintosh Programming Awards, May 1995.
  16.  
  17. What Anarchie Does
  18.  
  19. Anarchie is an FTP client for the Macintosh.  It will let you browse FTP sites, upload or download files, or find them using an archie server.  It requires System 7 and MacTCP 1.1 or later.  System 7.5 and MacTCP 2.0.6 or later are both highly recommended.
  20.  
  21. Features
  22.  
  23. Ñ╩Apple Guide (thanks to Quinn!).
  24. Ñ╩Internet Config support including post processing.
  25. Ñ SIVC support.
  26. Ñ╩Drag Manager support.
  27. Ñ╩AppleScritable and Recordable.
  28. Ñ╩Firewall support (SOCKS and Proxy FTP, but NOT CERN Proxy Web).
  29. Ñ╩MacBinary uploads and downloads.
  30. Ñ╩SITE INDEX support.
  31. Ñ╩Archie query support.
  32. Ñ╩Connectionless FTP.
  33. Ñ╩Comes with bookmarks to many popular sites.
  34. Ñ╩Fetches files from list windows with just a double-click.
  35. Ñ╩Supports UserLand╒s MenuSharing.
  36.  
  37. Using Anarchie
  38.  
  39. Anarchie is spelled that way, only the first letter is capitalised, and is pronounced ╥Anarchy╙, not ╥An archie╙.  
  40.  
  41. If you have System 7.5 or later, you can find out more useful information by using the Anarchie Guide, launch Anarchie and choose Anarchie Guide from the help (?) menu.
  42.  
  43. Preferences
  44.  
  45. Anarchie uses Internet Config to manage some of the preferences it shares with other Internet applications like NewsWatcher or FTPd.  If you haven╒t already configured your Internet Config preferences, you should do that first before you start Anarchie.  Launch Internet Config (which is included with this package) and go through each of the panels in turn and fill in your details (in particular you should fill in your Email address, configure your fonts and select your preferred Info-Mac, UMich and archie servers).  Save that and quit Internet Config.  Anarchie╒s use of Internet Config is described in more detail in a later section.
  46.  
  47. Now you can launch Anarchie.  Although Anarchie has some preferences of its own, you can pretty much ignore them for now.  If you are behind a company firewall, then you may need to read the section on Firewalls before continuing.
  48.  
  49. FTP
  50.  
  51. The main purpose of Anarchie is to allow you can browse or manipulate FTP sites.
  52.  
  53. To get started, choose Get╔ from the FTP menu.  This presents you with a window allowing you to type in the name of the machine you want to FTP to (eg ftp.share.com), as well as an optional path, username and password.  The path specifies which file or directory on the FTP site you wish fetched or displayed (eg peterlewis/).  The username and password specify who to log in as.  If you leave both of these blank, Anarchie will log in anonymously and supply your Email address (as configured in Internet Config) as your password.
  54.  
  55. You can also paste URLs like <ftp://ftp.share.com/peterlewis/> into this window and it will fill out the fields for you.  URLs are covered in more detail in a later section.
  56.  
  57. If you know part of the name of the file and the FTP site, then you may be able to use the Index feature.  Click the Index radio button (or press command-4) and then type in the machine name in the machine field, and the name you want to search for in the Index field (eg anarchie) and click the Index button.  Unfortunately, not all FTP sites support indexing, so some sites will return an error, or always return ╥Nothing Found╙.
  58.  
  59. Most of these actions will result in a window showing the progress of the listing, and when it is complete and new window listing all the files in the directory will show up.  If the listing fails for some reason, you can retry by clicking the Retry button, or if you want to change something (if you made a mistake when you typed the machine), then hold the control key down and click the Edit Retry button.  The control key almost always works like this, turning a direct action into an edit action, allowing you to make changes and then continue.
  60.  
  61. Note: Previous to version 1.5 of Anarchie, the option key had the effect that the control key now has.  The option key now means ╥close the parent window╙ just like it does in the Finder.
  62.  
  63. Note: If you click on the fields in the progress window (like Time Left), they will cycle through alternative displays.
  64.  
  65. The most common reason for FTP failures is that the FTP site is too busy to handle any more users at this time.  You can usually see this by looking in the Transcript window (described in more detail later).  It doesn╒t really help the situation for you to just keep clicking the Retry button until it gets through.  A better solution is to look for the file elsewhere.  Anarchie comes with a list of several dozen UMich and Info-Mac mirror sites (a mirror site is one that contains the same files as the original site, designed exactly to get around this problem of the servers being too busy).
  66.  
  67. The window that shows up listing the files in the directory (or the files found by the index command) is called a Listing Window and it described in a later section which also describes more FTP commands.
  68.  
  69. Archie
  70.  
  71. Anarchie also allows you to find files using Archie.  Archie is a system of big servers that catalogue all the anonymous FTP sites and allow users to ask where files are stored.  Unfortunately, they tend to be a bit behind the times and quite a bit flaky, but it can usually find a starting point when you have no idea where a file might be.  In general, if you know the file is on a UMich or Info-Mac mirror site (which is pretty much the case for almost any publicly distributable shareware or freeware Mac files), then you are better off using an FTP Index search or just browsing around a mirror site.
  72.  
  73. Choose Archie╔ from the File menu.  Select a server from the popup menu and type in what you want to search for in the Find field.  You can choose a more complicated search, such as patterns which let you put ? and *╒s in your search (just like MS-DOS or Unix file names) or a regular expression search, but for the most part a simple substring search will do the trick.  Click the Find button and Anarchie will query the archie server.  As noted above, the servers are a bit flaky at times, so you may want to repeat the query to a few other servers.
  74.  
  75. Note: Archie queries do not work through firewalls.  If you are behind a firewall, you can still use an FTP Index search, but not an archie search.
  76.  
  77. If your archie search returns some matches, they will show up in a Listing Window.
  78.  
  79. Listing Windows
  80.  
  81. The Listing Window listing files and directories on various FTP sites is the primary focus of most actions in Anarchie.  You can get a Listing Window in a number of ways, including those listed above.  Once you have one, you can open other windows by double-clicking folders just like in the Finder.  In fact, many Finder operations also work in a Listing Window (this is described in more detail in the Finder Shortcuts section).
  82.  
  83. To download a file, simply double-click it or drag it to the Finder.  
  84.  
  85. Note: You will need the Drag Manager installed to allow dragging.  I recommend installing System 7.5 to get the most out of Anarchie.
  86.  
  87. To view a text file in your favourite editor (as configured in Internet Config), select the file in the Listing Window and choose View Selection from the FTP menu.
  88.  
  89. To upload a file, choose Put╔ from the FTP menu, or drag it from the Finder.
  90.  
  91. To rename a file or directory, select it and then choose Rename╔ from the FTP menu and type in the new name.
  92.  
  93. To make a new directory in the Listing Window listing, choose Make Directory╔ from the FTP menu and type in the name of the new directory.
  94.  
  95. To delete a file or a directory (which probably has to be empty), select it and choose Delete from the FTP menu.
  96.  
  97. Warning: There is no undo for this.  Once you delete a file, the file is gone forever.
  98.  
  99. Note: Many of the above commands modify the listing that the Listing Window is displaying, but the Listing Window does not show any of these changes.  This is deliberate.  The Listing Window shows a snap shot of the listing at the time it was taken.  It makes no attempt to figure out if someone else is changing the directory, or if the above commands operated as expected (for example FTP servers often rename files or do other strange things when you upload files).  If you want the Listing Window to be refreshed to display any changes you or anyone else has made, simply choose Retry (command-R) from the File menu.
  100.  
  101. You can use the View menu to sort the listing window by the various colums.  You can also click on the column headers.  If you choose a View when no listing window is displayed, it will be used as the default.
  102.  
  103. To send raw FTP protocol commands to the server, use the Send FTP Command.  There are several things to note here:
  104. Ñ╩Raw FTP protocol commands and Unix FTP client commands are not the same thing ╨ the FTP protocol has no get, put, ls, del, etc commands and if you try to send them, Anarchie will complain and if you ignore Anarchie the FTP server will complain.
  105. Ñ Anarchie does not support allowing you to send file transfer or listing commands using the Send FTP Command.
  106. Ñ╩Anarchie transparently opens and closes FTP sessions as required, so if you send an FTP command that changes the state of the FTP server and then Anarchie closes and reopens the FTP session, that state change may be lost.
  107.  
  108. Bookmarks
  109.  
  110. Anarchie comes with a large list of predefined bookmarks listing many interesting sites on the Internet.  To use these, choose List Bookmarks from the File menu and Anarchie will open a Listing Window showing lots of interesting sites.
  111.  
  112. To create your own bookmark, select the directory or file you want to save and choose Save Bookmark╔ from the file menu.  You can also hold the control key down and drag the file or directory to the Finder.  If you place the new bookmark in the Bookmarks folder in Anarchie╒s folder then it will show up when you choose List Bookmarks.
  113.  
  114. Warning: If you save any bookmarks in the Bookmarks folder, be careful not to delete them when you update to a new version of Anarchie!
  115.  
  116. Note: Anarchie never saves passwords with bookmarks (although you can easily add a password to a bookmark yourself using HexEdit ╨ but then the security issues are on your head, not mine).  Also, only anonymous bookmarks will show up in the List Bookmarks listing ╨ you can still open them by double clicking them in the Finder.
  117.  
  118. You can edit existing bookmarks by holding down the control key while you double-click them, however saving them back will create a new bookmark unless you save them over the top of the existing bookmark.
  119.  
  120. Note: You should not change the Bookmarks file that comes with Anarchie without good reason, because when I release the next version of Anarchie it will have updates of some of the sites and you will have to make your changes again.
  121.  
  122. Internet Config
  123.  
  124. Anarchie uses Internet Config to configure most of its settings.  In particular it uses:
  125.  
  126. Ñ Your Email address as the anonymous password.
  127. Ñ Your preferred Info-Mac and UMich mirrors ╨ if you paste a path like ╥/info-mac/whatever╙ into the Get╔ window, it will be converted to a path to your preferred Info-Mac site (similarly for UMich paths)
  128. Ñ Your Screen font (and if IC ever supports it, your Listing Font).
  129. Ñ Your file mapping settings (to define types and application creators for downloaded files, as well as post processing options).
  130. Ñ Your helper settings (the editor helper is used for the View Selection command).
  131.  
  132. Although it is a bit of a nuisance having your preferences in a different application if you only have one or two applications, when you end up with five or more Internet applications, setting your preferences only once is definitely a win.  So take the time to set up your Internet Config preferences now and it╒ll save you some time when you download that next cool Internet application.
  133.  
  134. As a pay back to Internet Config, Anarchie will also let you update the server lists (Info-Mac, UMich, and Archie servers) to keep up to date with any changes.  Choose Update Server List from the Edit menu and Anarchie will download the new lists and add them to your Internet Config settings.  These lists change very slowly, so there is no need to do this more than a few times a year.
  135.  
  136. Shortcuts
  137.  
  138. Anarchie╒s Listing Windows support many of the Finder╒s Shortcuts (in the Finder, choose Shortcuts from the Help (?) menu to read about these).  In particular, you can:
  139.  
  140. Ñ sort the list by clicking the column headers.
  141. Ñ drag files to or from the Finder.
  142. Ñ type command-uparrow to open the parent window.
  143. Ñ hold the option key down while opening a new window to close the old one.
  144. Ñ close all windows using command-option-Close (then you can reopen some of them with the Log as described in a later section)
  145. Ñ open a parent of the current directory by holding the command key down and clicking in the window╒s title.
  146. Ñ typing the start of a name will select the first entry that starts with what you typed.
  147.  
  148. Also, pretty much anywhere you can do an action, if you hold the control key down Anarchie will let you edit the action first.  For example, hold the control key down while double-clicking a file and Anarchie will let you edit the path (this is useful if you want to list a different directory or do an index search ╨ don╒t forget to set the radio buttons to listing or index).
  149.  
  150. URLs
  151.  
  152. Universal Resource Locators (URLs) are the standard way of specifying locations on the Internet.  Anarchie uses FTP URLs either as inputs (by pasting them in to the Get╔ window) or as outputs (by selecting files or directories in listing windows and copying them).
  153.  
  154. An FTP URL looks like:
  155.  
  156. <ftp://user:password@host/path>
  157.  
  158. The ╥user:password@╙ is omitted for anonymous FTP.  The path can start or end with a slash (/).  If it starts with a slash (eg ftp://host//directory/), then it is an absolute path from the root of the FTP server╒s file system, otherwise it is relative to the default login location (which for anonymous FTP is often the root anyway).  If the path ends with a slash, then it is a directory, otherwise it is a file.
  159.  
  160. <ftp://ftp.share.com/peterlewis/> is an example URL.  It points to the machine ╥ftp.share.com╙ and the directory ╥peterlewis╙ relative to the default directory.
  161.  
  162. <ftp://ftp.share.com//ftp2/pub/peterlewis/0Programs.bin> is another example, this time it points to a file at the absolute path ╥/ftp2/pub/peterlewis/0Programs.bin╙
  163.  
  164. Note: Most web browsers attempt to do FTP and screw up relative paths (they assume all paths are absolute so <ftp://ftp.share.com/peterlewis/> fails).  MacWeb is the only web browser I know of that gets this right.
  165.  
  166. Log
  167.  
  168. Anarchie logs all your listings and file transfers (without saving your password).  You can display this log using the Show Log command in the Window menu.  This log is active, so you can double click an old entry in the log and it will refetch the file (or hold the control key down to allow you to edit the information before redoing it).  You can remove entries by selecting them and choosing Clear from the Edit menu (Select All or Find all at once  may be useful for cleaning out the log file).
  169.  
  170. Transcript
  171.  
  172. Anarchie keeps a transcript of all of the FTP sessions in the transcript window.  If an FTP request fails and you don╒t know why, try looking in the transcript window for more information ╨ the server may have closed down or be temporarily overloaded, or the files you are after may have moved.
  173.  
  174. Firewalls
  175.  
  176. A firewall is a machine that sits between your network and the rest of the Internet and limits the traffic that can pass between the two.  The primary reason for this is to ensure that your internal network is secure from crackers on the Internet.  Normally, a secure network is set up so that the firewall machine is the only machine that can send or receive packets from the Internet, and it can also send and receive packets from all the local machines.  When a local machine wants to talk to a remote machine on the Internet, it communicates via the firewall machine using a firewall protocol.  Normally this entails the local machine connecting to the firewall server and making requests and the firewall server then passes the request on to the remote machine and routes the replies back to you.
  177.  
  178. Anarchie supports two firewall protocols and a caching protocol which is similar to a firewall protocol:
  179.  
  180. SOCKS is a standard TCP firewall protocol.  It can work for any TCP connections (such as FTP, Finger, Gopher, Web, etc).
  181.  
  182. Proxy FTP is a pseudo standard FTP firewall protocol.  You FTP to the firewall FTP server, and it FTPs the file for you.
  183.  
  184. Alex is a pseudo standard caching system.  You FTP to the alex server and it gives you the file if it already has it, or FTPs it for you and keeps a copy for anyone else who wants one and feeds you the file.
  185.  
  186. Note: Anarchie does not support the CERN proxy web server.  I╒ve talked to the CERN people, but they need to add some more FTP support before I can use it.
  187.  
  188. Note: Archie queries will not work through any of the above firewalls.  Archie is a UDP protocol, the above are all FTP protocols (although future versions of SOCKS may support UDP).  You may be able to use a SOCKS compatible Telnet client to telnet to the archie servers and make your queries that way.
  189.  
  190. Contact your network administrator for more information about what (if any) firewalls are in place at your site.
  191.  
  192. AppleScript
  193.  
  194. Most things you can do from the user interface you can also do by controlling Anarchie with AppleScript.
  195.  
  196. Note: Many FTP commands take a long time to complete, so be careful to set the timeout or your script will terminate before the transfer is completed.
  197.  
  198. Example AppleScript:
  199.  
  200. tell application "Anarchie"
  201.   with timeout of 5 * 60 seconds
  202.     find "dehqx" server "archie.internic.net" matches 20 with window
  203.     fetch (file "HD:black-cat-startup.hqx") host "sumex-aim.stanford.edu" path "/info-mac/grf/black-cat-startup.hqx"
  204.     list (file "HD:listing") host "sumex-aim.stanford.edu" path "/info-mac"
  205.     store (file "HD:file") host "sumex-aim.stanford.edu" path "/incoming"
  206.   end timeout
  207. end tell
  208.  
  209. You can also use the ╥url╙ field to simplify some commands:
  210. or simpler:
  211.  
  212.     fetch url "ftp://sumex-aim.stanford.edu/info-mac/grf/black-cat-startup.hqx"
  213.     store (file "HD:file") url "ftp://user:password@host/path"
  214.  
  215. Anarchie also supports the standard GetURL suite.
  216.  
  217. Check out the example scripts and Anarchie╒s dictionary for more information.
  218.  
  219. You╒re on your own when it comes to Frontier, I╒ve included some stuff from Leonard Rosenthol, but I have no idea what it does - cool and froody things I expect!
  220.  
  221. Limitations
  222.  
  223. Anarchie requires System 7 and MacTCP 1.1 or later.  For large searches, large listings or many listings or searches or whatever, you may need to increase Anarchie╒s memory partition (use Get Info in the Finder to do this).  To display FTP sites, Anarchie assumes the directory listing will look something like a normal Unix one, if it doesn╒t, it won╒t work.  I have a document available on how Anarchie (and other programs) parse the LIST output, so if you are writing a server or client, let me know and I╒ll send you the document.
  224.  
  225. There may be problems with MS-Mail and/or Apple's CD-ROM driver v5.0.1.  The latter seems to poll the SCSI bus while there is no CD in and these polls somehow lock the machine up if they happen during Anarchie transfers.  RAM Doubler seems to be incompatible with serial networking (ARA, SLIP or PPP), and Anarchie seems to be very good at inducing a freeze when you are using RAM Doubler.
  226.  
  227. You may also have a problem over SLIP/PPP with your modem hanging up during a transfer if your modem init string does not contain &D0 (which tells it not to hang up if the buffer fills up).
  228.  
  229. Small Print
  230.  
  231. This program is Shareware, which means if you use it, you should send me US$10.  US dollars or personal checks in US dollars drawn on US banks are fine.
  232.  
  233. Site Licensing:
  234. World-Wide Source Code License: US$5000
  235. World-wide license: US$2000
  236. Universities or companies site license: US$500
  237. Curtin University and the University of Western Australia are exempt.
  238. Single-user license: US$10.
  239.  
  240. Use the Register provided to fill out the registration form and send (Email, Snail-Mail or FAX) it to my US distributer, Kagi Shareware.
  241.  
  242. If you purchase a site license, contact me for information on how to make this program automatically set the ╥I Paid╙ flag in the Preferences dialog.
  243.  
  244. You may distribute this program any way you wish as long as you don't charge for it (except for reasonable download costs).  I don╒t guarantee any support, but I always answer my Email.  If I don╒t answer Email its because your message didn╒t get to me, or my reply bounced, so try again and include a valid Internet address if you can.
  245.  
  246. You MAY NOT DISTRIBUTE this program on any disk costing more than $5 without my explicit permission.  You MAY NOT DISTRIBUTE this program on any CD without my explicit permission.
  247.  
  248. Warranty
  249.  
  250. This program should do what I╒ve described in this document.  If it doesn╒t, you can simply stop using it.  If you pay me, and within a year find that it doesn╒t do what I describe here, then you can notify me and I will refund your money and cancel your license.
  251.  
  252. Fine Print
  253.  
  254. Peter Lewis hereby disclaims all warranties relating to this software, whether express or implied, including without limitation any implied warranties of merchantability or fitness for a particular purpose.  Peter Lewis will not be liable for any special, incidental, consequential, indirect or similar damages due to loss of data or any other reason, even if Peter Lewis or an agent of his has been advised of the possibility of such damages.  In no event shall Peter Lewis be liable for any damages, regardless of the form of the claim.  The person using the software bears all risk as to the quality and performance of the software.
  255.  
  256. US Governement:
  257.         Government End Users:  If you are acquiring the Software and fonts
  258. on behalf of any unit or agency of the United States Government, the
  259. following provisions apply.  The Government agrees:
  260.         (i) if the Software and fonts are supplied to the Department of
  261. Defense (DoD), the Software and fonts are classified as "Commercial
  262. Computer Software" and the Government is acquiring only "restricted rights"
  263. in the Software, its documentation and fonts as that term is defined in
  264. Clause 252.227-7013(c)(1) of the DFARS; and
  265.         (ii) if the Software and fonts are supplied to any unit or agency
  266. of the United States Government other than DoD, the Government's rights in
  267. the Software, its documentation and fonts will be as defined in Clause
  268. 52.227-19(c)(2) of the FAR or, in the case of NASA, in Clause
  269. 18-52.227-86(d) of the NASA Supplement to the FAR.
  270.  
  271. Acknowledgements
  272.  
  273. A huge thanks goes to Quinn for the amazing Anarchie Guide.  If you like it, please send him a note and say so <quinn@cs.uwa.edu.au>.  Also, cc him on any guide-related bugs (please include the guide version number).
  274.  
  275. Thanks also go to Dmitry Boldyrev & Igor Livshits for the icons, and to various people on my beta list for their suggestions.  Quinn & Leonard get the award for most implemented suggestions.
  276.  
  277. Thanks again to Leonard for the Frontier stuff.  Don╒t ask me what it is, I╒m just including it - anything Leonard writes is certainly going to be good :-)
  278.  
  279. Thanks also to Chris W. Johnson and the folks at University of Texas at Austin for hosting the server lists fetched by ╥Update Server Lists╙.  You might like to check out their archive at <ftp://ftp.utexas.edu/pub/mac/>, or at <http://wwwhost.ots.utexas.edu/mac/main.html> if you want a WWW interface.
  280.  
  281. Thanks also to Jean-Pierre Kuypers for the french translation.
  282.